Mac Format 1994 August/August CD.bin/Shareware/Games/Redcoder/About Redcoder 2.0

Text File | 1994-06-05 | 17KB | 345 lines

About Redcoder 2.0 by Alex MacAulay:
-----------------------------------

Redcoder 2.0 is a greatly improved version of Redcoder 1.0. The most important
additions are:

- Features textual view windows displaying the contents of the core.
- Supports the proposed ICWS '94 standard by incorporating the pMARS assembler.
- Can use various different core patterns to display in the core window.

Redcoder 2.0 is email-ware! If you use this program at all please send me
a quick note at [e-mail] (or if it bounces from there, try
[e-mail] or [e-mail] or [e-mail]).
If you don't have e-mail access (or even if you do!), I would be very happy to
receive a postcard from you!

My address is:

  Alex MacAulay
  48 Culworth Ave
  Killara, NSW 2071
  Australia


Before starting:
---------------
Before you start using Redcoder you should already know what Core War is and
know the Redcode language. The information below assumes some knowledge of
these things. To find out about Core War, ftp to soda.berkeley.edu and
check out the "/pub/corewar" directory. It holds tutorials on Redcode, lots
and lots of example fighters, other Core War simulators for many different
operating systems, archives of newsgroup discussions and other goodies.


Getting started:
---------------
When you open Redcoder, you should get a dialog box which asks you to choose
a fighter list to open. An existing fighter list called "Fighter Examples" comes
with this release (in the "Fighters" folder), so you should open it to try Redcoder
out. You can also create a new, empty fighter list at this stage.

Three windows should appear when you open a fighter list. These are the
Status window, the Core window and the fighter list window. The status window
shows information about the current state of progress of a battle; the Core
window shows the contents of the core in a graphical format; and the fighter
list contains a list of fighters which you can load into the core.

Select a fighter from the fighter list such as "Redcoder Title" by clicking on
it. Then choose "Load Fighter" from the "Fighter" menu to load the fighter into
the core. Choose "Go" from the "Core" menu to start the fighter running.


Fighter list window:
-------------------
The fighter list window is titled with the name of the file holding the fighter
list. The "Fighter" menu contains various items which apply to fighters. See
the description of the "Fighter" menu for more details. For each fighter the
following information is shown:

  Name - The name of the fighter. If you include a ";name" comment then the name
    given in this comment will be used. Otherwise the file name will be used.
  Author - The author of the fighter. This is the name given in the ";author"
    comment or is empty if no such comment appeared in the fighter.
  Len - Length of the fighter in core locations.
  W - Number of wins.
  L - Number of losses.
  T - Number of ties.

Also, a diamond ('◊') is shown to the left of the name of the fighter if it is
known to have changed since the fighter was last compiled.

You can select fighters by clicking on them and select/deselect multiple fighters
by holding down the shift or command keys when you click. Also, you can use the
up and down arrows to navigate in the fighter list.


"Core" window:
-------------
This contains a visual representation of the core. Different patterns correspond
to different states of the core memory. To determine what each of these patterns
mean, you can display the "Legend" window (do this by choosing "Legend" under
the "Windows" menu). Drawing the changes to the core takes up a very large
proportion of the processing during a battle. Here are the options (in increasing
order of effect) to speed up a battle:

- Turn your monitor from colour to black and white mode (using the "Monitors"
  control panel).
- Use black and white and ensure you have "Use direct screen drawing" in the
  preferences turned on. Move the Core window to the very left edge of the
  screen so that the window's left border is not visible. Ensure that there
  are no windows obscuring any part of the core window. Redcoder will then
  draw directly to the screen giving an approximate 10 times speed increase.
  You'll notice it if it works! Note: this may crash on some machines.
- Hide the core window. Although you won't see the battle as it progresses,
  all the changes are still recorded and you can just show the core window
  again to see what has happened.
- Turn off drawing completely by toggling the "Draw Changes" menu item in
  the "Core" menu. This will not (visibly) record any changes made to the core
  and is the fastest possible way to run a battle.

Click on a core location to display it's contents in the Status window.

Command-click on a core location to place or remove a breakpoint at that
location. When a fighter tries to execute at location with a breakpoint, the
battle is paused and the location displayed in the Status window.

Option-click on a core location to open up a textual view window displaying the
contents of the core (and other useful information) of the locations around the
location you have clicked on.


"Status" window:
---------------
This window shows the status of the core and the battle. It is a floating window
which always stays in front of all other windows in the application.

The first line shows the number of cycles executed so far in the current
battle. If a tournament is running, the number of rounds left in the tournament
are also displayed (in brackets) on this line.

The second line shows the contents of a core location which you have clicked on
in the Core window. If it contains a breakpoint, a bullet ('•') is shown after
the contents. If you click on this line the location will be outlined in the
Core window. Command-click on this line to place a breakpoint at this
location. Option-click on this line to open a textual view window of the
core around the location.

The rest of the window displays information about the fighters in the battle.
Each line shows the patterns used for each fighter (for executing, executed,
changed and dead core locations) and the name of the fighter. If the fighter
is about to execute an instruction, then a little arrow will appear to the left
of the fighter. Click on the name of the fighter to replace the name with some
information about the fighter: the current number of tasks and the current
location of its program counter (or PC). Click there again to revert it back to
the name again. Click to the left of the name to outline the current location of
the fighter's program counter in the Core window. Option-click to the left of the
name to open a textual view of the core around the fighter's program counter.
Command-click to the left of the name to place a breakpoint at the fighter's
program counter.


"View" Window:
-------------
This window is very useful for debugging fighters. It displays a vertical list
of core locations with relevant information about each location. From left to
right, the information given is:

- The absolute address of the location. This will have a bullet ('•') beside it
  if there is a breakpoint at this location.
- A little triangular arrow (different types of arrows for each fighter) if
  the fighter will execute that instruction in it's next cycle.
- The contents of the location.
- The absolute addresses (in brackets) referred to by the a-field and b-field
  of the location. For example, if the instruction at location 100 was
  DAT.F $-100,$100 then the absoluted addresses would be (0,200).
- The number of processes waiting to execute at that location for each fighter.

Clicking on an instruction in the view window affects different places within
the core depending on where on the line you clicked. If you click on the
address, arrow area or opcode, then the location itself is affected. If you click
on the a-field or b-field then the location which that field refers to is
affected. For example, say location 100 was MOV #1,$50. Then if you clicked on
the a-field, location 100 would be affected since the '#' modifier refers to the
current location. Clicking on the b-field would affect location 150 since the
'$' modifier refers to the relative location. Say location 100 was change to
MOV #1,@50 and location 150 was DAT $0,$20. Then clicking on the b-field of
location 100 would affect location 170 (100+50+20). Just try this out a few
times to get the hang of it... Also, clicking on the absolute addresses in
brackets simply affects the location at those adrresses.

Now, what sort of ways can you affect locations? Well, clicking with the command
key down will place a breakpoint at that location. Clicking with the option key
will centre the view window onto that location. And simply clicking will hilite
that location (ie. outline it in the core and display it in bold-red-underline
in the view window).


"Legend" Window:
---------------
You can open the Legend window by choosing "Legend" from the "Windows" menu.
This displays the patterns used for each of the fighters. The meanings of each
of the types of patterns are:

Changed - the location has been modified.
Executing - there is a process waiting to execute at this location.
Executed - a process has executed the instruction at this location.
Dead - a process has died at this location.


"File" Menu:
-----------
New, Open…, Close, Save, Save As…, Save A Copy As…, Revert… - These menu items
  are all standard and act on Text files.
New Fighter List… - This creates a new, empty fighter list and opens it.
Open Fighter List… - This opens an existing fighter list.
Close Fighter List - This closes the current fighter list.
Preferences… - This brings up a dialog box with various option which are
  discussed in the Preferences section.
Quit - Exits from Redcoder.


"Edit" Menu:
-----------
Nothing unusual here. Note: Undoing is implemented for text editing. If you
make a mistake then you can choose Undo to undo it!


"Search" Menu:
-------------
This menu contains items which allow you to search and replace text in your
fighter source code and are self-explanatory.


"Core" Menu:
-----------
Go - Starts/continues a battle.
Step - Executes one cycle for each fighter participating in the battle.
Stop - Pauses execution of a battle.
Insert/Remove Breakpoint - Places or clears a breakpoint at the location
  currently shown in the Status window.
Open View Window - Opens a textual view window displaying the core centred
  around the location currently shown in the Status window.
Clear Breakpoints - Removes all breakpoints.
Clear Core - Stops a battle and erases the entire contents of the core.
Declare Round… - Allows you to declare the results of the battle without
  actually completing the battle. A dialog box will appear which has
  options of Win, Loss or Tie for each fighter.
Draw Changes - Turns drawing in the core on or off. This makes a MASSIVE
  difference to the speed of the battle.


"Fighter" Menu:
--------------
Most items in this menu can either be used when the Fighter list is in the front
(in which case the item applies to the selected fighters) or when an edit window
is in the front (in which case it applies to the fighter associated with the
edit window).

Load Fighter - Loads the fighter(s) into random locations in the core which do
  not overlap with other fighters already loaded in.
Load Fighter Into… - Does the same as Load Fighter except that it allows you
  to choose the loading location and the set of patterns used for each fighter.
Compile - Compiles the fighter(s) and saves the 'executable' code in the fighter
  list.
Disassemble - Creates a new edit window which contains the assembly code for
  the fighter(s).
Reset Score - Sets the wins, losses and ties for the fighter(s) to zero.
Add - Appends a fighter to the fighter list and associates the current edit window
  with that fighter. (This only applies to edit windows).
Add… - Brings up a file dialog box allowing you to choose several fighters to add
  to the fighter list.
Remove - Removes the fighter(s) from the fighter list.
Start Tournament… - Starts a tournament with the selected fighters (requires
  between two and four fighters). You can specify the number of rounds in the
  tournament. The results are stored, as usual, in the W L T columns of the
  fighters. You are given the option of resetting the numbres of wins, losses
  and ties of each of the fighters back to zero before the tournament starts.
Stop Tournament - This terminates a tournament which is currently in progress.


"Windows" Menu:
--------------
This menu has four initial items - Core, Fighters, Status and Legend. Choosing one
of these items shows the respective window and brings it to the front. If you have
any edit windows open, they also appear in this menu.


Preferences:
-----------
The "Preferences" item in the "File" menu allows you to modify the settings
for the fighter list. These settings only apply when the fighter list is being
used. (So if you set the core size to 100 in one fighter list, other fighter
lists will still use their own core size). Changing some of these settings may
require that all fighters are recompiled and/or the core be cleared. The settings
are:

Core size - Number of core locations.
Max tasks - Maximum number of tasks which can be allocated to each fighter.
Max fighter length - Maximum allowed length (in instructions) for a fighter.
Cycles before tie - Number of cycles in a battle before a tie is declared.
Max write distance - A non-standard setting which allows fighters to only
  change locations within a specified distance (on either side) of the
  currently executing instruction.
Tabs - The width (in spaces) of a tab in edit windows.
Font - The font used in edit windows.
Size - the text size used in edit windows.
Compile fighters when loading - When this is on, fighters are recompiled
  automatically before loading into the core if it is known that they have changed
  since they were last compiled. This ensures that you are testing an up-to-date
  fighter (in case you forgot to compile it first).
Beep at end of round - Beeps when the battle finishes.
Beep at breakpoint - Beeps when a breakpoint is reached.
Use ICWS ’88 Standard - This changes two things if turned on. Firstly, the compiler
  reverts to a (reasonably) standard ICWS ’88 compiler which doesn't allow the
  additions from the ICWS ’94 standard (such as opcode modifiers). Secondly, when
  displaying core locations, no opcode modifier is appended to the opcode.
Verbose compiler output - This is a pMARS option which gives detailed information
  as it compiles a fighter.
Denormalise address offsets - With this option turned on, addresses in the fields
  of an instruction which are greater than half the coresize are 'denormalised',
  that is they have the core size subtracted from them so that if the core size
  is 8000 then a field of 7998 would be displayed as -2. With this option turned
  off, fields are displayed as they are stored (ie. 7998 is displayed as 7998).


ICWS 88 Compatibility:
---------------------
Redcoder is almost fully ICWS '88 (International Core War Standard 1988)
compatible. The minor exceptions (actually additions) are:
- Optionally allows commas in between fields.
- All a- and b-modes are allowed. ICWS '88 does not allow some of these (for
  example, mov #a,#b).
- An extra mode, postincrement '>' (which is similar to the predecrement mode)
  is allowed.

There is also an optional extension, the maximum write distance, which prevents
a process from writing further than a specified distance from where it is
executing. This can be turned on/off in the Preferences dialog.

ICWS 94 Compatibility:
---------------------
Redcoder is compatible with the most recent ICWS ’94 draft (at the time of the
release of this program) and uses the pMARS assembler which is based on this
draft.

Credits:
-------
I have used some pieces of code from other authors in this program. They are:

pMARS by Albert Ma ([e-mail]), Nandor Sieben ([e-mail])
  Stefan Strack ([e-mail]) and Mintardjo Wangsaw
  ([e-mail]) - I have (with the authors’ permission) ported
  the assembler code in pMARS and used it as the assembler for Redcoder.

EMI88 by Mark A. Durham - A procedure which executes ICWS '88 code. The MARS
  used in Redcoder was based on this procedure but hardly resembles it anymore.

TE32K 1.2 by Roy Wood ([e-mail]) - a TextEdit replacement which allows
  documents larger than 32K and also has tabs. I've made a few little
  modifications to this.

Infinity Windoid 2.2 by Troy Gaul ([e-mail]) - A floating
  window WDEF which takes advantage of colour. This has no modifications at all.